home *** CD-ROM | disk | FTP | other *** search
/ Aminet 41 / Aminet 41 (2001)(Schatztruhe)[!][Feb 2001].iso / Aminet / util / wb / VisualPrefs.lha / VisualPrefs / DocsEnglish / VP-Developer.doc < prev    next >
Text File  |  1999-12-13  |  7KB  |  158 lines
  1.  
  2. Last update: 8.12.99
  3.  
  4.                                Introducing
  5.  
  6.                     THE VISUALPREFS DEVELOPER INTERFACE
  7.  
  8.                             A work in progress
  9.  
  10.  
  11. If you're a developer, you can take advantage of some features of VisualPrefs.
  12.  
  13. Although there's not a full developer API for VisualPrefs yet, it's already
  14. possible to use the BOOPSI classes that VisualPrefs adds to the system.
  15.  
  16. The purpose of these classes is to give programmers an easy way to get the
  17. "VisualPrefs look", without having to wait for me to implement a patch for
  18. their applications in VisualPrefs. ;-)
  19.  
  20. Currently there's just one class:
  21.  
  22. "tbiclass" - the titlebar image class
  23.  
  24. This class provides the most commonly used images for gadgets added by
  25. applications to the titlebar of their windows. Examples of this are the
  26. ubiquitous "iconify" gadget or DirOpus 5's "padlock" gadget.
  27.  
  28. All programs using this class will automatically get the same look for their
  29. titlebar images if VisualPrefs is running. This is probably better than
  30. having myriads of different versions of the same image...
  31.  
  32. You can use "tbiclass" just like "sysiclass"; they're both sub-classes of
  33. "imageclass". A "tbiclass" image can be created by calling NewObject() with
  34. the following tags:
  35.  
  36. SYSIA_DrawInfo - This is absolutely mandatory. You MUST pass a DrawInfo
  37.                  pointer to "tbiclass" or NewObject() will fail.
  38.  
  39. SYSIA_Which - To specify which image you want; currently there are six image
  40.               types:
  41.  
  42.               POPUPIMAGE    - A MUI "pop-up" titlebar gadget image
  43.               MUIIMAGE      - A MUI "settings" titlebar gadget image
  44.               SNAPSHOTIMAGE - A MUI "snapshot" titlebar gadget image
  45.               ICONIFYIMAGE  - An "iconify" titlebar gadget image
  46.               PADLOCKIMAGE  - A DirOpus "padlock" titlebar gadget image
  47.               TBFRAMEIMAGE  - A general-purpose empty titlebar gadget image
  48.  
  49. IA_Width, IA_Height - These are only recognized by the TBFRAMEIMAGE type;
  50.                       the other image types ignore them and always have
  51.                       the same size of the depth gadget image.
  52.  
  53. SYSIA_ReferenceFont - This is only recognized by the TBFRAMEIMAGE type;
  54.                       the other image types ignore it and always have
  55.                       the same height of the depth gadget image.
  56.  
  57. TBIA_FullFrame - This is only recognized by the TBFRAMEIMAGE type; set it
  58.                  to TRUE to get an image which also contains an inner frame,
  59.                  if the current style has one. This is best suited when the
  60.                  image contents are graphic in nature. Set it to FALSE to
  61.                  get an image which has at most the outer frame; this is
  62.                  instead best suited when the image must contain text (as
  63.                  the inner frame might be too small to render the text into).
  64.                  The default is FALSE. (Available since VisualPrefs 41.38)
  65.  
  66. You can also use this tag with GetAttr():
  67.  
  68. TBIA_ContentsBox - To ask the image about the position and size of its
  69.                    actual "contents box" relative to the image itself.
  70.                    Said box is the part where, if you need to, you can
  71.                    add any further custom imagery. This probably only
  72.                    makes sense with TBFRAMEIMAGE images. To position
  73.                    correctly the box, you should add its Left and Top
  74.                    offsets to those of the image. Note that, even within
  75.                    the returned dimensions, you should always leave a
  76.                    small space (like two pixels) around your imagery,
  77.                    to achieve better-looking results. This is a read-only
  78.                    attribute; the value you pass to this tag must be a
  79.                    pointer to an IBox structure. Do NOT pass a longword
  80.                    pointer! (Available since VisualPrefs 41.35)
  81.  
  82. Of course, if NewObject() fails, you should provide a built-in fallback image
  83. for your titlebar gadget. However, I have released a disk-based freeware
  84. "tbiclass" image class (dev/gui/titlebar_ic.lha) which you can include in the
  85. distribution of your applications. This class will provide the needed images
  86. and will be automatically replaced by the VisualPrefs one if it is present.
  87. Therefore, you can keep your built-in images very simple, or not have
  88. them at all ;-)
  89.  
  90. If you use TBFRAMEIMAGE to make your own special titlebar images, you can
  91. add contents to it in two ways: by setting the NextImage field to the address
  92. of your custom inner imagery, or by sub-classing "tbiclass" and redefining
  93. the IM_DRAW/IM_DRAWFRAME methods (of course, in this case you must let the
  94. superclass do its rendering first!).
  95.  
  96. It's important to note that all "tbiclass" image instances will have an
  97. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  98. place your titlebar gadgets accordingly. The reason for this apparently
  99. strange behavior is that Intuition titlebar gadget images, too, work this
  100. way, and we should try to stay as compatible with Intuition as possible.
  101.  
  102. Also, make sure you adjust your gadget's size if necessary, to adapt it
  103. to the returned image's size.
  104.  
  105. An example of all this could be:
  106.  
  107.    ...
  108.  
  109.    /* Create the image */
  110.  
  111.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  112.                                                   SYSIA_DrawInfo,dri,
  113.                                                   TAG_END)))
  114.    {
  115.       iconifyimage = builtin_iconifyimage;
  116.    }
  117.  
  118.    /* Use the image */
  119.  
  120.    gad->GadgetRender = iconifyimage;
  121.    ...
  122.  
  123.    /* Free the image */
  124.  
  125.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  126.  
  127.    ...
  128.  
  129. That's all. The real include file for "tbiclass" is in the Aminet stand-alone
  130. release, anyway all you need in order to use "tbiclass" in your applications
  131. is to paste the following few lines at the beginning of your source code. :-]
  132.  
  133. ------- cut here -------8<------- cut here -------8<------- cut here -------
  134.  
  135. #define POPUPIMAGE    (101)
  136. #define MUIIMAGE      (102)
  137. #define SNAPSHOTIMAGE (103)
  138. #define ICONIFYIMAGE  (104)
  139. #define PADLOCKIMAGE  (105)
  140. #define TBFRAMEIMAGE  (106)
  141.  
  142. #define TBIA_Dummy       (TAG_USER + 0x0B0000)
  143. #define TBIA_ContentsBox (TBIA_Dummy + 0x0001)
  144. #define TBIA_FullFrame   (TBIA_Dummy + 0x0002)
  145.  
  146. ------- cut here -------8<------- cut here -------8<------- cut here -------
  147.  
  148. There's already an application using "tbiclass", ViNCEd by Thomas Richter.
  149.  
  150. I hope you will also support "tbiclass" and contribute this way to finally
  151. give a consistent appearance to all titlebar gadgets used in applications!
  152.  
  153. Thank you,
  154.                                       Massimo Tantignone (tanti@intercom.it)
  155.  
  156.  
  157.  
  158.